home *** CD-ROM | disk | FTP | other *** search
- *****************************************************************************
-
- Please do no distribute this version of EnhancedJoystickLib!!!
-
- This version is only a Beta release and has been released into
- the InterNet blitz-list mailing list.
-
- If I get no major bugs within a few days of this release, I will
- release a full version (with an allocated lib number) which can
- be distributed.
-
- Note
- ====
- Make sure that you save anything you write which uses this
- library as ASCII as well as tokenised. This is to ensure easy
- transition when the full release version is distributed.
-
-
- *****************************************************************************
-
- Command List
- ============
- n.l=IsLowLevel
- SetJoyPortType port,type
- n.b=GetJoyPortType(port)
- n.b=NewJoyB(port)
- n.b=OldJoyB
- n.b=NewJoyX(port)
- n.b=OldJoyX
- n.b=NewJoyY(port)
- n.b=OldJoyY
- n.b=NewJoyR(port)
- n.b=OldJoyR
- n.l=NewJoyData(port)
- n.l=OldJoyData
- n.b=JoyRToJoyX(rotation)
- n.b=JoyRToJoyY(rotation)
- n.b=JoyXYToJoyR(x,y)
-
-
- *****************************************************************************
-
- Library Name: EnhancedJoystickLib
- Library Version: 1.2 Beta
-
- Library Number: 11 (temporary, will change in the future!!!)
- Written by: Chi Wai Lee
- Copyright: 1994 Spiral Vortex Productions.
- Dated: 16/7/94
-
- E-Mail Contact: Chi Wai Lee@2:2500/167.9 (FidoNet)
- @39:138/16.9 (AmigaNet)
- C.W.Lee-CSSE93@cs.bham.ac.uk (InterNet)
- CCA93039@ibm3090.bham.ac.uk (InterNet)
-
- Snail-Mail : Chi Wai Lee
- 9 Fraser Road
- Greet, Birmingham
- United Kingdom
- B11 2NA
-
- *****************************************************************************
-
- READ THIS
- =========
-
- THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED BY
- APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
- COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS
- IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
- INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
- MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
- RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS WITH
- YOU. SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF
- ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-
- IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
- WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
- REDISTRIBUTE THE PROGRAMS AS PERMITTED ABOVE, BE LIABLE TO YOU
- FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
- CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
- THE PROGRAMS (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
- BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
- PARTIES OR A FAILURE OF THE PROGRAMS TO OPERATE WITH ANY OTHER
- PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
- THE POSSIBILITY OF SUCH DAMAGES.
-
-
- *****************************************************************************
-
- AND THIS
- ========
-
- No warranty, either express or implied, is made with respect to
- the fitness or merchantability of EnhancedJoystickLib.
-
- Chi Wai Lee (referred to as "the author"), reserve the right to
- not develop any future versions of EnhancedJoystickLib.
-
- The author will try to make a good faith attempt at correcting
- any problems if any are discovered, but is in no way required,
- nor bound to correct them.
-
- The author neither assume nor accept any responsibility for the
- use or misuse of these programs. They also will not be held
- liable for damages or any compensation beyond the original
- registration fee due to loss of profit or any other damages
- arising out of the use, or inability to use this program.
-
- The author will not be liable for any damage arising from the
- failure of these programs to perform as described, or any
- destruction of other programs or data residing on a system
- attempting to run the programs. While we know of no damaging
- errors, the user of these programs uses it at his or her own
- risk.
-
-
- *****************************************************************************
-
- Conditions Of Use
- =================
-
- 1)..You may copy and distribute verbatim copies of the programs'
- executable code and documentation as you receive it, in any
- medium, provided that you publish only the original, unmodified
- program, with all copyright notices and disclaimers or warranty
- intact and including all the accompanying documentation, example
- files and anything else that came with the original.
-
- 2)..You may use this program for an evaluation period of 30 days.
- Thereafter, you *HAVE* to register or acknowledge the use of this
- program with the author (see condition 3). If you do not register
- after the elapse of the evaluation period (see condition 3), you
- are in violation of the Conditions Of Use (see condition 6.)
-
- 3)..The normal evaluation period of this program is 30 days. You
- may extend this period to 60 days if you acknowledge the use of
- this program by sending the author a postcard. Doing so will only
- extend the evaluation period and does not change any other
- Conditions Of Use.
-
- 4)..For this library to be incorporated into any distributed (in
- any medium) software of type ShareWare, Public Domain, FreeWare,
- etc., (i.e. Not commercial - Fee for use must be below 20 UK
- pounds or equivalant cost) this library *MUST* be registered with
- the author.
-
- 5)..The use of this library for commercial software (Fee for use
- above 20 UK pounds or equivalant) is prohibited. You *MUST*
- contact the author for a commercial license agreement.
-
- 6)..If you are in violation of any of the above Conditions of Use
- you *MUST* remove all trace of this program and any accompanying
- material.
-
- 7)..If any software using this library is distributed (see
- condition 4) without the author of the software being registered.
- I have the right to remove the offending software from any
- storage medium.
-
-
- *****************************************************************************
-
- Registering
- ===========
-
- The registration fee for this program is *ONLY* 5 UK pounds for a
- period of one year, thereafter for you to continue use of this
- program, you must re-register or you will be in violation of the
- Conditions Of Use, or 10 UK pounds for an indefinite period.
-
- No other form of currency will be accepted!!!
-
- Registering allows the use of any version of this library in any
- of your programs during the period in which you are registered.
- Registering does not give you any extra, new, faster, etc.,
- functions although you may gain more help from me.
-
- This software is distributed in the *TRUE* sense of ShareWare.
-
-
- *****************************************************************************
-
- Requirements
- ============
-
- Most of these functions *REQUIRE* C='s lowlevel.library as found
- in WorkBench 3.1 and some versions of WorkBench 3.0.
-
-
- *****************************************************************************
-
- Installation
- ============
-
- 1)..Temporary installation.
- Copy the .obj file into your BlitzLibs:Userlibs/ directory and do
- a RELOAD LIBS from the compiler menu within Blitz. The new
- commands will be usuable until you quit.
-
- 2)..Normal installation.
- Copy the .obj file into you BlitzLibs:Userlibs/ directory. Now
- run the tool MAKEDEFLIBS. This should create a new DEFLIBS file
- which contains the new commands. These new commands will now be
- usable whenever you load Blitz. Note that the commands aren't
- available for any currently running Blitz. You should do a RELOAD
- LIBS from the compiler menu to enable the new commands.
-
- If you cannot find the MAKEDEFLIBS tool, it may be archived in a
- file called libtools.lha within the includes/ directory.
-
- If you still can't get it to work, contact me and I'll try to
- sort it out.
-
-
- *****************************************************************************
-
- Brief Comment
- =============
-
- The reason I have written these function is that I needed a way
- of reading the joystick port's second fire button. Obviously, I
- came across Richard Elmore's JoyC() function but from my tests
- showed that it was not 100% reliable when reading the second fire
- button on joystick port 1.
-
- My tests showed that it works fine in test situations (i.e. loop
- testing), but failed (always reported button two is pressed) when
- put in a real life situation (my current project.) I have traced
- the problem to the way the joystick port uses a
- capacitor-potentiometer for the second fire button unlike the
- normal fire button which uses a switch.
-
- [Richard - contact me if you want a bit more info on the prob.]
-
- I therefore set about on writing my own routines to read the
- joystick port. By coincidence, I came across C='s
- lowlevel.library which has a very comprehensive joystick port
- command set. Since this library is based around C='s
- lowlevel.library, this library is therefore upwardly compatible
- with future Amiga OS' (If the Amiga survives)
-
- The way this library has been designed allows for a single
- command to read the complete state of the selected joystick port
- and then allow following commands to use the stored state for
- it's data.
-
- For example:
-
- x.b=JoyX(1)
- y.b=JoyY(1)
- r.b=JoyR(1)
- b.b=JoyB(1)
-
- can produce inconsistent results, the JoyR function may return
- different values than the above JoyX and JoyY functions.
-
- On the other hand, using the functions in this library...
-
- x.b=NewJoyX(1)
- y.b=OldJoyY
- r.b=OldJoyR
- b.b=OldJoyB
-
- will ensure consistent results due to all the results are from
- *ONE* specific reading of the joystick port.)
-
- In addition to these new joystick reading command, there are
- several conversion functions (e.g. convert a JoyR result into a
- JoyX result.)
-
- There is however one disadvantage, namely speed. The actual
- joystick port reading is done using a function from the
- lowlevel.library and to be honest isn't very fast, but only
- slightly slower than the normal Blitz joystick function.
-
- But then again there are some speed advantages as well. Due to
- the way this library has been designed, you only need to read the
- joystick port once but still able to get several results from
- this read.
-
- For example:
-
- b.b=NewJoyB(1)
- x.b=JoyX(1)
- y.b=JoyY(1)
- r.b=JoyR(1)
-
- would be *MUCH* slower than
-
- b.b=NewJoyB(1)
- x.b=OldJoyX
- y.b=OldJoyY
- r.b=OldJoyR
-
- as the OldJoy... functions are using a stored state of the
- joystick port instead of reading in a new value.
-
-
- *****************************************************************************
-
- Version 0.9 (13/7/94) First Public Beta Release
-
- Version 1.0 (13/7/94)
- Decided to halt release for a few hours...
- Changed some of the names of the functions. Will not affect
- anyone cos no one has this library yet <G>
-
- Version 1.1 (14/7/94) First Public Beta Release, Again
- Add SetJoyPortType() and GetJoyPortType() functions.
-
- Version 1.2 (16/7/94) Second Public Beta Release
- SetJoyPortType() does not update the OldJoy... data anymore.
- GetJoyPortType() now accepts a port number.
-
-
- *****************************************************************************
-
- All references to joystick port assumes 0 being the standard
- mouse port, 1 being the standard joystick port. The
- lowlevel.library's ReadJoyPort() function suggests that it can
- also accept port 2 and 3 (four player adaptor???)
-
- I have not really tested for these, but know that if you enter
- any values other than 0-3 will always result in NULL returns.
-
- In this Beta release, I have included C='s lowlevel.library. This
- is strictly speaking, illegal but I have no KS1.3, KS2.04
- machines to test this library on so am putting my trust in you
- guys for beta testing this library on other machine
- configurations.
-
-
- =============================================================================
-
- Function: IsLowLevel
- =========
- Syntax: n.l=IsLowLevel
- Description:
-
- This function will return the address of where the
- lowlevel.library is loaded. If the lowlevel.library cannot be
- loaded, a value of 0 is returned.
-
- WARNING
- =======
- Make sure you test for this before using any of the below
- functions which require the lowlevel.library.
-
-
- -----------------------------------------------------------------------------
-
- Statement: SetJoyPortType
- =========
- Syntax: SetJoyPortType port,type
- Description:
-
- This statement sets the specified port to a type of input device.
-
- Type Device
- 0 AutoSense
- 1 Game Controller (CD^32 gamepad, etc.) (7 fire buttons)
- 2 Mouse
- 3 Joystick (upto two fire buttons)
-
- Please note that this command *ONLY* affects the joystick port
- functions within this library. The default start-up setting is
- AutoSense. Also note that the way AutoSense works is that it
- scans the port several times and decides depending on what type
- of data is retrieved, what type of controller is attached. This
- can cause a slight delay and sometimes spurious results for the
- first reading of the port.
-
- The best (suggested) method is to set the port to a specific
- controller type before using the port, therefore resulting in a
- much faster read time and accurate readings.
-
- Setting the port to mouse has no real use due to the fact that no
- mouse support commands have been included. The standard Blitz
- mouse commands are sufficient for most needs.
-
- NOTE
- ====
- The method in which the Game Controller (gamepad) has 7 fire
- buttons cause the read commands to be slower. This is not due to
- shoddy programming but due to the way the fire buttons have to be
- encoded into time based patterns which naturally requires a
- certain time to decode back again.
-
- WARNING
- =======
- Setting the port type to anything other than the above specified
- ones can cause errors. Do so at your own risk!!!
-
- HINT (1.2)
- ====
- AutoSense will cause all read commands to that port to be slower.
-
- QUESTION
- ========
- I noticed that the lowlevel.library's joystick port commands can
- read upto 4 devices. I have tried using a parallel four player
- adaptor and have not been able to get *ANY* feedback from them. I
- also noticed that ports 2 and 3 (joysticks 3 and 4) can *ONLY* be
- set to Game Controller.
-
- This leads me to a conclusion that a four player adaptor will be
- release specifically for the CD32 (maybe usable on us normal
- Amigas) which allows for four gamepads (like the Sega and SNES
- thingies.)
-
-
- -----------------------------------------------------------------------------
-
- Function: GetJoyPortType
- =========
- Syntax: n.b=GetJoyPortType(port)
- Description:
-
- This function returns a result which represents what type of
- controller code was used for the specified port. Note that this
- function only represents the controller code and not the
- controller type used.
-
- To find the controller type, you will need to do a SetJoyPortType
- to activate AutoSense and then wait for some input, before using
- GetJoyPortType again.
-
- Result Controller Type
- 0 Not Available
- 1 Game Controller (CD^32 gamepad, etc. 7 buttons)
- 2 Mouse
- 3 Joystick (upto two buttons)
- 4 Unknown
-
-
- -----------------------------------------------------------------------------
-
- Function: NewJoyB
- =========
- Syntax: n.b=NewJoyB(joystick port)
- Description:
-
- This function returns a byte which represents the current state
- of the joystick port fire buttons (all 7 of them, if you are
- using a CD^32 gamepad or equivalant.)
- The state of the port is also stored for use by the OldJoy...
- functions.
-
- Dec Bit Button
- 1 0 Grey - Play/Pause; Middle Mouse
- 2 1 Charcoal - Reverse
- 4 2 Charcoal - Forward
- 8 3 Green - Shuffle
- 16 4 Yellow - Repeat
- 32 5 Red - Select; Left Mouse; Joystick Button One
- 64 6 Blue - Stop; Right Mouse; Joystick Button Two
-
-
- -----------------------------------------------------------------------------
-
- Function: OldJoyB
- =========
- Syntax: n.b=OldJoyB
- Description:
-
- This function returns the joystick port fire buttons of the last
- read joystick port state. See *NewJoyB* for return values.
-
-
- -----------------------------------------------------------------------------
-
- Function: NewJoyX
- =========
- Syntax: n.b=NewJoyX(joystick port)
- Description:
-
- This function returns the current state of the joystick port X
- direction. If the joystick is held left, a value of -1 is
- returned. If the joystick is held right, a value of +1 is
- returned. Otherwise a value of 0 is returned.
- The state of the port is also stored for use by the OldJoy...
- functions.
-
-
- -----------------------------------------------------------------------------
-
- Function: OldJoyX
- =========
- Syntax: n.b=OldJoyX
- Description:
-
- This function returns the joystick port X direction of the last
- read joystick port state. See *NewJoyX* for return values.
-
-
- -----------------------------------------------------------------------------
-
- Function: NewJoyY
- =========
- Syntax: n.b=NewJoyY(joystick port)
- Description:
-
- This function returns the current state of the joystick port Y
- direction. If the joystick is held up, a value of -1 is returned.
- If the joystick is held down, a value of +1 is returned.
- Otherwise a value of 0 is returned.
- The state of the port is also stored for use by the OldJoy...
- functions.
-
-
- -----------------------------------------------------------------------------
-
- Function: OldJoyY
- =========
- Syntax: n.b=OldJoyY
- Description:
-
- This function returns the joystick port Y direction of the last
- read joystick port state. See *NewJoyX* for return values.
-
-
- -----------------------------------------------------------------------------
-
- Function: NewJoyR
- =========
- Syntax: n.b=NewJoyR(joystick port)
- Description:
-
- This function returns the current state of the joystick port R
- direction.
- The state of the port is also stored for use by the OldJoy...
- functions.
-
- Direction Return value
- Up 0
- Up-Right 1
- Right 2
- Down-Right 3
- Down 4
- Down-Left 5
- Left 6
- Up-Left 7
- No Direction 8
-
-
- -----------------------------------------------------------------------------
-
- Function: OldJoyR
- =========
- Syntax: n.b=OldJoyR
- Description:
-
- This function returns the joystick port R direction of the last
- read joystick port state. See *NewJoyR* for return values.
-
-
- -----------------------------------------------------------------------------
-
- Function: NewJoyData
- =========
- Syntax: n.l=NewJoyData(joystick port)
- Description:
-
- This function calls the lowlevel.library's ReadJoyPort() function
- and returns the resultant raw code.
- The state of the port is also stored for use by the OldJoy...
- functions.
-
-
- -----------------------------------------------------------------------------
-
- Function: OldJoyData
- =========
- Syntax: n.l=OldJoyData
- Description:
-
- This function returns the result of the previous ReadJoyPort()
- function call.
-
-
- -----------------------------------------------------------------------------
-
- Function: JoyRToJoyX
- =========
- Syntax: n.b=JoyRToJoyX(rotation)
- Description:
-
- This function returns the X direction from the specified R
- direction.
-
-
- -----------------------------------------------------------------------------
-
- Function: JoyRToJoyY
- =========
- Syntax: n.b=JoyRToJoyY(rotation)
- Description:
-
- This function returns the Y direction from the specified R
- direction.
-
-
- -----------------------------------------------------------------------------
-
- Function: JoyXYToJoyR
- =========
- Syntax: n.b=JoyXYToJoyR(x,y)
- Description:
-
- This function returns the R direction from the specified X and Y
- directions.
-
-
- =============================================================================